Getting started: Add docs for property actions

Use the just added example to add another section to the docs.

diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index 4848ee55a9536a186b55c8bf9e5e801c882f9981..1c60e59693d58b9acc57cdb1f3d830c2035e2aad 100644 (file)
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -420,6 +420,7 @@ HTML_IMAGES = \
        $(srcdir)/images/getting-started-app6.png                       \
        $(srcdir)/images/getting-started-app7.png                       \
        $(srcdir)/images/getting-started-app8.png                       \
+       $(srcdir)/images/getting-started-app9.png                       \
        $(srcdir)/images/exampleapp.png
 
 # Extra options to supply to gtkdoc-fixref

diff --git a/docs/reference/gtk/getting_started.xml b/docs/reference/gtk/getting_started.xml
index 89ef881c1d186696481ac1f15a4f3a9fd31363a8..99ab4adda5a7f3487267d79b5888efd11a9e9763 100644 (file)
--- a/docs/reference/gtk/getting_started.xml
+++ b/docs/reference/gtk/getting_started.xml
@@ -327,7 +327,7 @@
       is launched with commandline arguments.</para>
 
       <para>To learn more about GApplication entry points, consult the
-      GIO <ulink url="https://developer.gnome.org/gio/2.36/GApplication.html#GApplication.description">documentation</ulink>.
+      GIO <ulink url="https://developer.gnome.org/gio/2.36/GApplication.html#GApplication.description">documentation</ulink>.</para>
 
       <informalexample>
         <programlisting><xi:include href="../../../../examples/application1/exampleapp.c" parse="text"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
@@ -902,5 +902,73 @@ example_app_window_init (ExampleAppWindow *win)
         </mediaobject>
       </informalfigure>
     </section>
+    <section>
+      <title>Properties</title>
+
+      <para>Widgets and other objects have many useful properties.</para>
+
+      <para>Here we show some ways to use them in new and flexible ways,
+      by wrapping them in actions with #GPropertyAction or by binding them
+      with #GBinding.</para>
+
+      <para>To set this up, we add two labels to the header bar in our
+      window template, named @lines_label and @lines, and bind them to
+      struct members in the private struct, as we've seen a couple of times
+      by now.</para>
+
+      <para>We add a new "Lines" menu item to the gears menu, which
+      triggers the show-lines action:</para>
+
+      <informalexample>
+        <programlisting><xi:include href="../../../../examples/application9/gears-menu.ui" parse="text"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
+      </informalexample>
+
+      <para>To make this menu item do something, we create a property
+      action for the visible property of the @lines label, and add it to the
+      actions of the window. The effect of this is that the visibility
+      of the label gets toggled every time the action is activated.</para>
+
+      <para>Since we want both labels to appear and disappear together,
+      we bind the visible property of the @lines_label widget to the
+      same property of the @lines widget.</para>
+
+      <informalexample>
+        <programlisting>
+...
+
+static void
+example_app_window_init (ExampleAppWindow *win)
+{
+  ...
+
+  action = (GAction*) g_property_action_new ("show-lines", priv->lines, "visible");
+  g_action_map_add_action (G_ACTION_MAP (win), action);
+  g_object_unref (action);
+
+  g_object_bind_property (priv->lines, "visible",
+                          priv->lines_label, "visible",
+                          G_BINDING_DEFAULT);
+}
+
+...
+        </programlisting>
+        <para>(<ulink url="https://git.gnome.org/browse/gtk+/tree/examples/application9/exampleappwin.c">full source</ulink>)</para>
+      </informalexample>
+
+      <para>We also need a function that counts the lines of the currently
+      active tab, and updates the @lines label. See the
+      <ulink url="https://git.gnome.org/browse/gtk+/tree/examples/application9/exampleappwin.c">full source</ulink>
+      if you are interested in the details.</para>
+
+      <para>This brings our example application to its final appearance:</para>
+
+      <informalfigure>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="getting-started-app9.png" format="PNG"/>
+          </imageobject>
+        </mediaobject>
+      </informalfigure>
+    </section>
   </section>
 </chapter>

diff --git a/docs/reference/gtk/images/getting-started-app9.png b/docs/reference/gtk/images/getting-started-app9.png
new file mode 100644 (file)
index 0000000..e547ed7
Binary files /dev/null and b/docs/reference/gtk/images/getting-started-app9.png differ